table of contents
TRACEF(3) | LTTng Manual | TRACEF(3) |
NAME¶
tracef - LTTng-UST printf(3)-like interface
SYNOPSIS¶
#include <lttng/tracef.h>
#define tracef(fmt, ...)
Link with -llttng-ust.
DESCRIPTION¶
The LTTng-UST tracef() API allows you to trace your application with the help of a simple printf(3)-like macro. The fmt argument is passed directly to the fmt parameter of vasprintf(3), as well as the optional parameters following fmt.
To use tracef(), include <lttng/tracef.h> where you need it, and link your application with liblttng-ust. See the EXAMPLE section below for a complete usage example.
Once your application is instrumented with tracef() calls and ready to run, use lttng-enable-event(1) to enable the lttng_ust_tracef:* event.
The tracef() events contain a single field, named msg, which is the formatted string output.
If you need to attach a specific log level to a tracef() call, use tracelog(3) instead.
See also the LIMITATIONS section below for important limitations to consider when using tracef().
EXAMPLE¶
Here’s a usage example of tracef():
#include <stdlib.h> #include <lttng/tracef.h> int main(void) {
int i;
for (i = 0; i < 25; i++) {
tracef("my message: %s, this integer: %d", "a message", i);
}
return EXIT_SUCCESS; }
This C source file, saved as app.c, can be compiled into a program like this:
cc -o app app.c -llttng-ust
You can create an LTTng tracing session, enable the tracef() events, and start the created tracing session like this:
lttng create my-session lttng enable-event --userspace 'lttng_ust_tracef:*' lttng start
Next, start the program to be traced:
./app
Finally, stop the tracing session, and inspect the recorded events:
lttng stop lttng view
LIMITATIONS¶
The tracef() utility macro was developed to make user space tracing super simple, albeit with notable disadvantages compared to custom, full-fledged tracepoint providers:
Thus, tracef() is useful for quick prototyping and debugging, but should not be considered for any permanent/serious application instrumentation.
See lttng-ust(3) to learn more about custom tracepoint providers.
BUGS¶
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
RESOURCES¶
COPYRIGHTS¶
This macro is part of the LTTng-UST project.
This macro is distributed under the GNU Lesser General Public License, version 2.1 <http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>. See the COPYING <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more details.
THANKS¶
Thanks to Ericsson for funding this work, providing real-life use cases, and testing.
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey.
AUTHORS¶
LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently maintained by Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
SEE ALSO¶
tracelog(3), lttng-ust(3), lttng(1), printf(3)
06/05/2016 | LTTng 2.9.0-pre |